Copyright © 2000-2001 J. Peter Hoddie. All rights reserved
Version 1.0; July 8, 2001
Latest version available at www.hoddie.net/xmltorefmovie
Version 1.0. July 7, 2001. Added versions of application for Windows and Mac OS X. Update for QuickTime 5 including new data rates and Sorenson 3. Enhanced error reporting.
June 26, 2001. Add link to QTRM Maker.
May 19, 2001. Updated broken link in documentation.
Version 0.94, February 14, 2001. Fixed bug in version element where mask and value were reversed.
Version 0.93, September 7, 2000. Added the ability to specify component subtype by hex value.
Version 0.92, May 2000 (unreleased). Added support for the choke speed attribute, the ability to specify the default movie path using a relative URL, and the ability to reference the default movie from a refmovie element.
The conversion is performed by dropping the QTRM file onto the XMLtoRefMovie application. The XML file must have a file name extension of ".qtrm". The output file is name is automatically generated by XMLtoRefMovie by removing the ".qtrm" extension and replacing it with a ".mov" extension. Therefore, if the input file name "test.qtrm" the output file name will be "test.mov" in the same folder as "test.qtrm". If there is already a file named "test.mov" in that folder, it will be deleted and replaced with the new version.
If there are any problems in the QTRM file, XMLtoRefMovie displays an alert describing the first error that occurred together with its line number.
Developer Dave Egbert has created a tool to assist in creating QTRM files. It still requires a basic knowledge of XML and the QTRM file format, but you won't have to memorize all the tags and attributes supported by XMLtoRefMovie to create a QTRM file. .QTRM Maker is available for free download from Dave's site.
The contents of the QTRM file are based on the capabilities of QuickTime's reference movie feature. Support for reference movies was first released in QuickTime 3.0. A QuickTime reference movie is a special kind of QuickTime movie file. Instead of containing media data such as audio and video, it contains a description of different conditions on the user's machine. Based on which conditions are actually present, a different movie can be played. For example, the QuickTime reference movie can have a list of movies at various bit-rates, one for 28.8 modem another for DSL and another for a T1 line. QuickTime chooses the movie that most closely matches the user's actual bandwidth.
Selecting a movie based on bandwidth is the most common use of a QuickTime reference movie, but there are many other possibilities. Other selection criteria include the version of QuickTime installed, whether or not a particular component is installed, the relative CPU speed, the user's language preference, and many others.
A QuickTime reference movie may also contain a single embedded QuickTime movie to be used in the situation where all the other selection criteria are not met. This makes it easy to provide a default movie or image when the user is unable to view the actual movie. This default movie is also displayed when the reference movie is played by other software that can playback QuickTime movies, such as Real Player or Microsoft Windows Media Player, but that doesn't support the full feature set of QuickTime.
XML2RefMovie is the only tool that gives you access to all the features of QuickTime reference movies. Some of the capabilities of QuickTime reference movies are quite sophisticated and therefore may not be that easy to use.
This document does not attempt to describe QuickTime reference movies in detail. The follow references provide more information about QuickTime reference movies.
QuickTime Alternate Data Rates - Apple's description of the data rate feature of QuickTime reference moviesMakeRefMovie - Apple's graphical tool for creating reference movies
MediaCleaner Demo - Terran Interactive's tool for compressing movies which includes support for creating QuickTime reference movies
Ice Floe dispatch 15 - Mike's definitive technical documentation on the capabilities and format of QuickTime reference movies
An QTRM file is based on XML. Here's a simple example of a QTRM file that selects from three movies based on the data rate of the viewer's Internet connection:
<qtrefmovie><refmovie src="test_28.mov" data-rate="28.8 modem" /> <refmovie src="test_56.mov" data-rate="56k modem" /> <refmovie src="test_t1.mov" data-rate="t1" /></qtrefmovie>
Every QTRM consists of a single "qtrefmovie" element. There can only be one "qtrefmovie" element and it must be the first and only element in the file.
With the "qtrefmovie" element there can be one or more "refmovie" elements. Each "refmovie" element must contain a "src" attribute to indicate the URL of the media to use if that "refmovie" element best matches the selection criteria. Each "refmovie" element also contains at least one, but potentially multiple, selection criteria. In the above example, all the movies specify the data rate as the sole selection criteria.
The media referred to by the URL in the "src" attribute does not have to be a QuickTime movie file. Any QuickTime supported media type can be listed. Both relative and absolute URLs are supported as well. The following example shows this by providing dial-up modem users with a streaming media presentation over RTSP and higher bandwidth users with a Fast-Start version of the media.
<qtrefmovie><refmovie src="rtsp://example.hoddie.net/test.mov" data-rate="56k modem" /> <refmovie src="http://example.hoddie.net/test_t1.mov" data-rate="dual isdn" /></qtrefmovie>
Another useful way to select which movie to use is based on the version of QuickTime the user has installed. The following example shows this.
<qtrefmovie><default-movie src="file:///mydisk/movies/you-need-qt-4.mov" /> <refmovie src="rtsp://example.hoddie.net/test.mov" quicktime-version="4" /></qtrefmovie>
The "default-movie" element provides a movie to be used if none of the "refmovie" element's selection criteria are met. The "default-movie" element contains only one attribute, the "src" attribute. Because the default movie is copied into the reference movie file created by XMLtoRefMovie, the URL specified in the "src" attribute must be available when XMLtoRefMovie is run. The default movie URL may be either an absolute or relative URL. If it is an absolute URL, it must use the file:, http: or ftp: URL schemes. The default-movie URL does not have to reference a QuickTime movie, but rather any QuickTime supported media file format.
The "quicktime-version" attribute in the "refmovie" element indicates the minimum QuickTime version that must be installed on the user's machine in order to view this content. The following example shows another way to use the "quicktime-version" attribute to select between different movies.
<qtrefmovie><refmovie src="test.swf" quicktime-version="4" /> <refmovie src="test.smil" quicktime-version="4.1" /> <refmovie src="test_plus.smil" quicktime-version="4.1.1" /></qtrefmovie>
In this example, if the user has QuickTime 4, a Flash movie file is used. If the user has QuickTime 4.1, a SMIL document is used because SMIL support was first provided in QuickTime 4.1. Finally, if the user has QuickTime 4.1.1 or better, a different version of the SMIL document is used which contains features not available in QuickTime 4.1. Note that no default movie is specified in this document, so if the user has a version of QuickTime prior to 4.0, the file will fail to load.
In the previous example, the presence of SMIL support was determined by checking the QuickTime version number. Rather than assuming that SMIL is present in a particular version of QuickTime, it is possible to explicitly check to see if SMIL is installed.
<qtrefmovie><default-movie src="need_new_qt.mov"/> <refmovie src="test.smil"><component type="movie-importer" subtype="SMIL" /></refmovie></qtrefmovie>
This example uses the more complex form of the "refmovie" element. Instead of all the attributes being contained within the "refmovie" tag, the complex "component" attribute is contained in the body of the "refmovie" element as its own element. The "component" element provides a way to check for the presence of a particular QuickTime software component. In this example, the component being checked for is the SMIL movie import component.
In some cases, all the criteria of more than one "refmovie" element can be met. If no other information is provided, QuickTime will choose one of the "refmovie" elements to use. The "priority" attribute can be used to break a tie, as shown in the following example.
<qtrefmovie><refmovie src="test.smil" priority="high"><component type="movie-importer" subtype="SMIL" /></refmovie> <refmovie src="test.smil" priority="normal"><component type="movie-importer" subtype="mp3" /></refmovie></qtrefmovie>
In this case, if the user has both MP3 and SMIL support, the SMIL movie will be selected because the corresponding "refmovie" element has a higher priority.
The following example shows another use of the "component" element. The QuickTime installer gives the user the choice not to install all of QuickTime. This provides for a faster download time for users downloading QuickTime over a slow Internet connection. In order to detect when the user tries to use a component that isn't installed, some components that are not installed are still included in the list of installed components. Therefore, simply checking for the existance of a particular component may not correctly indicate if it is installed. By using the "flags" and "flags-mask" attributes of the "component" element, it is possible to determine if a component is available.
<qtrefmovie><refmovie src="hasVR.mov" priority="high"><component type="media-handler" subtype="pano" flags-mask="0x20000000"/></refmovie> <refmovie src="noVR.mov" priority="low"/></qtrefmovie>
The first "refmovie" element checks to see if QuickTime VR is installed by checking the component flags of the panora media handler. If the component is present in the system component list, and its flags indicate that it is installed, the QuickTime VR movie is displayed, otherwise the "noVR.mov" file is used. Note that the "priority" attribute is used to make the "hasVR.mov" "refmovie" element a higher priority, to avoid a conflict with the "no VR" "refmovie".
This section has provided examples of the most commonly used features of QuickTime reference movies. XMLtoQTRM provides support for all the features of QuickTime reference movies. A complete description of the QTRM file format is provided in the next section.
The QTRM file format is based on XML 1.0. If the formal XML specification is too intimidating, a less formal introduction is available.
The outermost element is "qtrefmovie". The "qtrefmovie" element has no attributes. There can only be one "qtrefmovie" element per QTRM file.
There are two elements that can be contained with a "qtrefmovie" element, "default-movie" and "refmovie".
Note: XMLtoQTRM supports both decimal and hex values any place that it accepts a number. Therefore priority="16" and priority="0x10" are equivalent.
The "default-movie" attribute can appear, at most, once within a "qtrefmovie" element. Its sole attribute, "src", provides a relative or absolute URL to a media file to be used if none of the selection criteria describing the "refmovie" elements is satisfied. The contents of the "src" URL are copied into the movie file created by XMLtoQTRM. The URL is not included in the output file, only the data it refers to.
The "refmovie" element must appear at least once, and typically several times, within a "qtrefmovie" element.
Each "refmovie" element must the "src" attribute to indicate the media to access if it is selected. The "src" attribute contains a URL, which can be either absolute or relative. The media data referenced by this URL is not accessed at the time XMLtoQTRM creates the reference movie. There is a special case supported for the "src" element. If the value is empty (i.e. src="") then the default movie will be used. This capability is necessary in some situations due to the way in which QuickTime determines when to use the default movie.
A "refmovie" element must contain at least one selection criteria. These are defined by the "data-rate", "language", "priority", "cpu-speed", and "quicktime-version" attributes as well as the "component" and "version" sub-elements.
The "data-rate" attribute can either contain either an enumeration or a number. The enumeration values are {14.4 modem, 28.8 modem, 56k modem, isdn, dual isdn, 256 kbps, 384 kbps, 512 kbps, 768 kbps, 1 mbps, t1, intranet}. The numbers represent the number of tens of bits per second of the connection. For example, 2800 indicates a 28.8 modem and 5600 indicates a 56k modem, etc. In general, the enumeration values should be used as these match the settings in QuickTime's Connection Speed control panel.
The "language" attribute can contain either an enumeration or a number. The enumeration values are language names from the set {english, french, german, italian, dutch, swedish, spanish, danish, portuguese, norwegian, hebrew, japanese, arabic, finnish, greek, icelandic, maltese, turkish, croatian, tradchinese, urdu, hindi, thai, korean}. A number may also be specified. QuickTime's language codes are taken from the Mac OS header file "Script.h" starting with langEnglish. The language enumeration supported by XML2RefMovie doesn't include all QuickTime supported languages, so the facility to specify a number instead can be used to indicate these languages. For example Quechua has a value of 132. The "language" attribute is available starting with QuickTime 4.0.
The "priority" attribute can contain either an enumeration or a number. The enumeration values are {high, normal, low}. These map to the values {100, 50, 0}. Numbers can also be specified. QuickTime attaches no meaning to the particular values used in the priority attribute other than to compare their relative values.
The "cpu-speed" attribute can contain either an enumeration of a number. The enumeration values are {very slow, slow, medium, fast, very fast}. These map to the values {100, 200, 300, 400, 500}. Numbers can also be specified. These values are based on machine speed measurements. A description of how these values map to particular PowerPC or Pentium models is beyond the scope of this document. The "cpu-speed" attribute is available starting with QuickTime 4.0.
The "quicktime-version" attribute contains a QuickTime version number in one of three forms: "4", "4.1" or "4.1.1" The value is taken to mean the lowest required version of QuickTime. The "quicktime-version" attribute is a special case of the more general "version" sub-element that has been provided for authoring convenience.
The "src-choke-speed" attribute can contain either an enumeration or a number. The enumeration values are {14.4 modem, 28.8 modem, 56k modem, isdn, dual isdn, t1, intranet, movie}.If a number is used, it is interpreted in the same way as in the "data-rate" attribute. The "src-choke-speed" attribute specifies the maximum data rate at which the referenced movie should be downloaded. QuickTime will attempt to limit the download speed to the value specified. If the "movie" enumeration value is used, the movie will be downloaded at the data rate of the movie referenced.
The "component" sub-element of the "refmovie" element contains at least two attributes, "type" and "subtype" and optionally "manufacturer", "flags", "flags-mask" and "min-version". The "type", "subtype", "manufacturer", "flags", and "flags-mask" attributes describe the fields of a QuickTime ComponentDescription data structure that is used to call FindNextComponent to check for the presence of a particular component.
The "type" attribute contains either an enumeration or a four character code. The enumeration values are {image-decompressor, media-handler, graphics-importer, movie-importer, visual-effect}. The four character code indicates the type of the component to be checked for. The enumeration values map to the following four character codes {'imdc', 'mhlr', 'grip', 'eat ', 'imdc'}.
The "subtype" attribute contains either an enumeration, a four character code, or a number using hex notation. The enumeration values are {sorenson, sorenson 3, qdesign2, purevoice, h.263, flash, mpeg-1, streaming, vr, 3d, mp3, smil, flash}. The four character code indicates the subtype of the component to be checked for.
The "manufacturer" attribute contains either an enumeration or a four character code. The enumerations values are{apple, sorenson, sorenson media, qualcomm, qdesign, voxware, fraunhofer}. The four character code indicates the manufacturer of the component to be checked for. This attribute is rarely used.
The "flags" attribute contains a number. The number indicates the value of the flags field of the component to be checked for. This attribute is rarely used, and when it is, it is usually used together with the "flags-mask"
The "flags-mask" attribute contains a number. The number indicates the value of the flags-mask field of the component to be checked for. This attribute is rarely used, and when it is, it is usually used together with the "flags" attribute.
The "min-version" attribute contains a number, typically using hex notation. The number indicates the minimum required version number of the component specified by the "type", "subtype", "manufacturer", "flags", and "flags-mask" attributes. If the "min-version" attribute is not present, a default value of zero is used.
The "version" sub-element of the "refmovie" element contains a selector "attribute" which indicates what to check for the version number of. It then provides a choice of two different ways to test the value of the version, either by comparing it to a minimum value or by testing the values of certain bits of the result. The "version" element provides a way to check Gestalt values. For a complete list of Gestalt selectors and their values, refer to the Mac OS header file "Gestalt.h" or Apple's Gestalt Manager documentation.
The "selector" attribute contains a four character code. This value corresponds to a gestalt selector. Each "version" element must contain exactly one "selector" attribute.
The "min-value" attribute contains a number. This number indicates the smallest value that the value returned by the gestalt selector could have in order for the version element's criteria to be satisfied. If the "min-value" attribute is used, the "value" and "mask" attributes cannot be used.
The "value" and "mask" attributes both contain numbers, typically using hex notation. The result of the gestalt selector is logically and-ed- with the value of "mask" and then the result of that operation is tested for equality with the vale of the "value" attribute. This provides a way to check for the values of bits within the gestalt value. If the "value" and "mask" attributes are used, the "min-value" attribute may not be used. The "value" and "mask" attributes must appear together.
In order to keep track of which version of XMLtoRefMovie created a particular QuickTime reference movie, XMLtoRefMovie adds an extra atom to the movie it creates. The atom adds twelve additional bytes to the movie file. The atom has a type of 'XMRM' and consists of a single long integer which indicates which version of the XMLtoRefMovie writer was used to create the file. The 'XMRM' is ignored by QuickTime.